docs: polish the factory developer tool pages (audit 4/5) - #856

Summary

Part 4 of 5 of the Warp Factories docs audit (split out of #852). Brings the Factory MCP tool table up to date and cleans up the API pages, which still carried the most GitBook-era formatting in the section.

Changes

factory-mcp.mdx

• Adds the tools the server registers but the table omitted: list_inbox, attach_integration, and start_factory_learning (the factory_learning flag is on in production). The learning phase itself has no page yet; that's a follow-up.
• Says once, up front, that a "task" is what the MCP tools call a factory work item.
• "What you can use it for" mentions the inbox and attaching integrations; Related pages use plain links.

api-and-sdk/index.mdx

• Removes the note about oz commands in examples (the page has none).
• Slashed shorthand written out ("succeeded/failed", "headers/status", "retries/timeouts", "TS/JS", "Sync + async"); bold pseudo-headings and a curly apostrophe removed; --- separators dropped.
• The key endpoints list becomes a normal bulleted list; the agent configuration list gets dash-separated descriptions; a ## Related pages section is added. The bundled-skill table stays here as the single home.

api-and-sdk/quickstart.mdx

• The meta-opener ("This quickstart walks you through...") becomes a direct lead; placeholders use ALL_CAPS (YOUR_API_KEY, ENV_ID, RUN_ID) per the style guide, with the wk- prefix fact kept in prose; "CI/CD" written out; Next steps use the quickstart shape (recap line, plain links).

api-and-sdk/demo-sentry-monitoring-with-sdk.mdx

• The page opens with a heading (## Turn production errors into draft pull requests) and an intro, then the video. The original ### sat directly under the frontmatter H1, skipping a level, so it's an H2 now. Curly quotes, the "What Ben covers" pseudo-heading, and the arrow shorthand are gone; a ## Related pages section is added.

factory-api.mdx, developer-tools.mdx, webhooks.mdx, webhooks/vercel.mdx

• factory-api.mdx: the recap sentence after the endpoint-family table is cut; list items capitalize consistently; the SDK comment "With the pagination scheme wired" becomes plain English; "task" becomes "work item"; "adhoc" becomes "ad hoc".
• developer-tools.mdx: plain list links; "Webhooks" becomes "Custom webhooks" to match the page it links to.
• webhooks.mdx: the secret paragraph's dangling "which covers all three" is reworded; Related pages use plain links (also on the Vercel page).

Content design plan

Audience and JTBD: A developer wiring a factory into their own tooling through MCP, the REST API, or a webhook.

Problem: The MCP table was missing three tools, and the API pages still read like the GitBook originals.

Goals: The tool table matches the server; the API pages follow the same conventions as the rest of the section.

Content type: Existing reference, quickstart, and feature pages; no new pages.

Unverified claims

None.

Documentation risk

Risk: engineering-review-required
Rationale: Adds three Factory MCP tools to the reference table; everything else is wording, formatting, and cross-links.
Source files consulted: warp-server/router/handlers/public_api/factory_mcp/server.go@cf7e9149d422, warp-server/config/prod.yaml@cf7e9149d422
Engineering review status: pending
Docs override: none

Validation

npm run build, check_links.py --internal-only (0 broken), and style_lint.py were run on the combined audit branch that these files were split from.

Plans:

• Audit and polish the Warp Factories docs (PR into hyc/factories-overview-copy)

Co-Authored-By: Warp agent@warp.dev